home *** CD-ROM | disk | FTP | other *** search
/ Gold Medal Software 4 / Gold Medal Software - Volume 4 (Gold Medal) (1994).iso / os2 / common.arj / COMMON.H < prev    next >
C/C++ Source or Header  |  1994-08-06  |  95KB  |  1,829 lines
  1. //-------------------------------------------------------------------------
  2. // Copyright (c) 1993 by Lawrence W. Salomon, Jr.  All rights reserved.
  3. //
  4. // This file may not be modified in any form without the expressed,
  5. // written consent of the author.  See also the licensing agreement
  6. // included with this package for more information.
  7. //-------------------------------------------------------------------------
  8. #ifndef COMMONLIB_INCLUDED
  9. #define COMMONLIB_INCLUDED
  10.  
  11. #ifndef OS2_INCLUDED
  12. #error You must include <os2.h> prior to including <common.h>
  13. #endif
  14.  
  15. //-------------------------------------------------------------------------
  16. // By defining the following symbols, the corresponding functions are
  17. // defined:
  18. //
  19. // INCL_CMNBUF  -       Buffer routines
  20. // INCL_CMNCOM  -       Communication routines
  21. // INCL_CMNDBG  -       Debugging routines
  22. // INCL_CMNFIL  -       File routines
  23. // INCL_CMNLST  -       Linked list routines
  24. // INCL_CMNMEM  -       Memory routines
  25. // INCL_CMNOBJ  -       Object routines
  26. // INCL_CMNSET  -       Set routines
  27. // INCL_CMNSIG  -       Signal routines
  28. // INCL_CMNSPR  -       Sprite routines
  29. // INCL_CMNSTR  -       String routines
  30. // INCL_CMNVIO  -       VIO routines
  31. // INCL_CMNWIN  -       PM routines
  32. //-------------------------------------------------------------------------
  33. #ifdef INCL_COMMONALL
  34. #define INCL_CMNBUF
  35. #define INCL_CMNCOM
  36. #define INCL_CMNDBG
  37. #define INCL_CMNFIL
  38. #define INCL_CMNLST
  39. #define INCL_CMNMEM
  40. #define INCL_CMNOBJ
  41. #define INCL_CMNSET
  42. #define INCL_CMNSIG
  43. #define INCL_CMNSPR
  44. #define INCL_CMNSTR
  45. #define INCL_CMNVIO
  46. #define INCL_CMNWIN
  47. #endif                           // #ifdef INCL_COMMONALL
  48.  
  49. #include <cmndefs.h>
  50.  
  51. #pragma pack(1)
  52.  
  53. #ifdef __cplusplus
  54. extern "C" {
  55. #endif                           // #ifdef __cplusplus
  56.  
  57. USHORT EXPENTRY CmnQueryHandle(LHANDLE lhHandle);
  58. //-------------------------------------------------------------------------
  59. // This function returns the type of the specified handle
  60. //
  61. // Input:  lhHandle - specifies the handle to query
  62. // Returns:  QH_* constant
  63. //-------------------------------------------------------------------------
  64.  
  65. BOOL EXPENTRY CmnQueryHandleInfo(LHANDLE lhHandle,PVOID pvInfo);
  66. //-------------------------------------------------------------------------
  67. // This function returns information about the handle specified.
  68. //
  69. // Input:  lhHandle - specifies the handle to query
  70. // Output:  pvInfo - points to the buffer which received the result.  The
  71. //                   size of this buffer depends on the handle type.
  72. // Returns:  TRUE if successful, FALSE otherwise
  73. //-------------------------------------------------------------------------
  74.  
  75. BOOL EXPENTRY CmnSetHandleInfo(LHANDLE lhHandle,PVOID pvInfo);
  76. //-------------------------------------------------------------------------
  77. // This function sets certain attributes about the handle specified.
  78. //
  79. // Input:  lhHandle - specifies the handle to query
  80. //         pvInfo - points to the buffer which received the result.  The
  81. //                  size and type of this buffer depends on the handle type.
  82. // Returns:  TRUE if successful, FALSE otherwise
  83. //-------------------------------------------------------------------------
  84.  
  85. VOID EXPENTRY CmnQueryVersion(PUSHORT pusMajor,
  86.                               PUSHORT pusMinor,
  87.                               PUSHORT pusRev);
  88. //-------------------------------------------------------------------------
  89. // This function returns the major, minor, and revision numbers.
  90. //
  91. // Output:  pusMajor - points to the variable that received the major
  92. //                     version number
  93. //          pusMinor - points to the variable that received the minor
  94. //                     version number
  95. //          pusRev - points to the variable that received the revision
  96. //                   version number
  97. //-------------------------------------------------------------------------
  98.  
  99. #ifdef INCL_CMNBUF
  100. //-------------------------------------------------------------------------
  101. // Buffer routines
  102. //-------------------------------------------------------------------------
  103.  
  104. BOOL EXPENTRY CmnBufCompressBytes(PBYTE pbInBuf,
  105.                                   ULONG ulSzInBuf,
  106.                                   PBYTE pbOutBuf,
  107.                                   PULONG pulSzOutBuf);
  108. //-------------------------------------------------------------------------
  109. // This function uses a run-length encoding algorithm to attempt to
  110. // compress the contents of a specified buffer.
  111. //
  112. // Input:   pbInBuf - points to the buffer to compress
  113. //          ulSzInBuf - specifies the size of the buffer pointed to by
  114. //                      pbInBuf
  115. //          pbOutBuf - points to the buffer to hold the result.  If NULL,
  116. //                     no results are written.
  117. // Output:  pulSzOutBuf - points to the variable containing the size of
  118. //                        the compressed buffer.
  119. // Returns:  TRUE if successful, FALSE otherwise.
  120. //-------------------------------------------------------------------------
  121.  
  122. BOOL EXPENTRY CmnBufDecompressBytes(PBYTE pbInBuf,
  123.                                     ULONG ulSzInBuf,
  124.                                     PBYTE pbOutBuf,
  125.                                     PULONG pulSzOutBuf);
  126. //-------------------------------------------------------------------------
  127. // This function uses a run-length encoding algorithm to decompress
  128. // the contents of a specified buffer that was compressed using
  129. // CmnBufCompressBytes().
  130. //
  131. // Input:   pbInBuf - points to the buffer to decompress
  132. //          ulSzInBuf - specifies the size of the buffer pointed to by
  133. //                      pbInBuf
  134. //          pbOutBuf - points to the buffer to hold the result.  If NULL,
  135. //                     no results are written.
  136. // Output:  pulSzOutBuf - points to the variable containing the size of
  137. //                        the decompressed buffer.
  138. // Returns:  TRUE if successful, FALSE otherwise.
  139. //-------------------------------------------------------------------------
  140.  
  141. BOOL EXPENTRY CmnBufEncryptBytes(PBYTE pbInBuf,ULONG ulSzBuf,PBYTE pbOutBuf);
  142. //-------------------------------------------------------------------------
  143. // This function encrypts the contents of a buffer using a not-too-secure
  144. // algorithm based on the XOR operation.  The resulting buffer is always
  145. // of the same size as the input.
  146. //
  147. // Input:  pbInBuf - points to the buffer to be encrypted
  148. //         ulSzBuf - specifies the size of the buffer pointed to by pbInBuf
  149. //         pbOutBuf - points to the buffer to hold the encrypted result
  150. // Returns:  TRUE if successful, FALSE otherwise.
  151. //-------------------------------------------------------------------------
  152.  
  153. BOOL EXPENTRY CmnBufDecryptBytes(PBYTE pbInBuf,ULONG ulSzBuf,PBYTE pbOutBuf);
  154. //-------------------------------------------------------------------------
  155. // This function decrypts the contents of a buffer encrypted using
  156. // CmnBufEncryptBytes().  The resulting buffer is always of the same size
  157. // as the input.
  158. //
  159. // Input:  pbInBuf - points to the buffer to be decrypted
  160. //         ulSzBuf - specifies the size of the buffer pointed to by pbInBuf
  161. //         pbOutBuf - points to the buffer to hold the decrypted result
  162. // Returns:  TRUE if successful, FALSE otherwise.
  163. //-------------------------------------------------------------------------
  164. #endif                           // #ifdef INCL_CMNBUF
  165.  
  166. #ifdef INCL_CMNCOM
  167. //-------------------------------------------------------------------------
  168. // Communication routines
  169. //-------------------------------------------------------------------------
  170.  
  171. COMERROR EXPENTRY CmnComOpenConnection(PCCOPENINFO pcoiInfo,
  172.                                        PHCCCONNECT phccConnect);
  173. //-------------------------------------------------------------------------
  174. // This function opens a connection with the desired attributes and
  175. // returns the connection handle.
  176. //
  177. // Input:  pcoiInfo - points to the CCOPENINFO structure describing the
  178. //                    type of connection desired
  179. // Output:  phccConnect - points to the variable which receives the result
  180. // Returns:  COM_ERR_* constant
  181. //-------------------------------------------------------------------------
  182.  
  183. COMERROR EXPENTRY CmnComCloseConnection(PHCCCONNECT phccConnect);
  184. //-------------------------------------------------------------------------
  185. // This function closes the specified connection and destroys the connection
  186. // handle.
  187. //
  188. // Input:  phccConnect - points to the variable containing the handle to
  189. //                       destroy.  On exit, this variable contains NULL.
  190. // Returns:  COM_ERR_* constant
  191. //-------------------------------------------------------------------------
  192.  
  193. COMERROR EXPENTRY CmnComWaitConnection(HCCCONNECT hccServer,
  194.                                        PHCCCONNECT phccConnect);
  195. //-------------------------------------------------------------------------
  196. // For server connections, this function waits until a client connects to
  197. // the server connection, then creates a new connection for private
  198. // communication to the client.  This leaves the server connection free
  199. // to service other requests.  If a client connection is specified, this
  200. // function returns COM_ERR_NOTSERVER.
  201. //
  202. // Input:  hccServer - handle to the server connection
  203. // Output:  phccConnect - points to the variable which receives the new
  204. //                        connection once a client connects to the
  205. //                        connection specified by hccServer
  206. // Returns:  COM_ERR_* constant
  207. //-------------------------------------------------------------------------
  208.  
  209. COMERROR EXPENTRY CmnComSendControl(HCCCONNECT hccConnect,ULONG ulCtrlCode);
  210. //-------------------------------------------------------------------------
  211. // This function sends a control packet to the other end of the connection.
  212. // The semantics of the various control codes are as follows:
  213. //
  214. //    CSC_CTRL_CLOSE - indicates that the connection should be closed.
  215. //    CSC_CTRL_RESET - indicates that the connection should be reset.
  216. //                     "Reset" is an abstract term that should be defined
  217. //                     by the application.
  218. //
  219. // Specifying any other value for ulCtrlCode returns COM_ERR_BADCONTROL.
  220. //
  221. // Input:  hccConnect - handle to the connection
  222. //         ulCtrlCode - specifies a CSC_CTRL_* constant
  223. // Returns:  COM_ERR_* constant
  224. //-------------------------------------------------------------------------
  225.  
  226. COMERROR EXPENTRY CmnComReadData(HCCCONNECT hccConnect,
  227.                                  PVOID pvBuf,
  228.                                  PULONG pulSzBuf);
  229. //-------------------------------------------------------------------------
  230. // This function reads data from the connection.
  231. //
  232. // Input:  hccConnect - handle to the connection
  233. //         pulSzBuf - points to the variable containing the size of the
  234. //                    buffer pointed to by pvBuf.  On exit, this variable
  235. //                    contains the number of bytes read.
  236. // Output:  pvBuf - points to the buffer to receive the data
  237. // Returns:  COM_ERR_* constant
  238. //-------------------------------------------------------------------------
  239.  
  240. COMERROR EXPENTRY CmnComWriteData(HCCCONNECT hccConnect,
  241.                                   PVOID pvBuf,
  242.                                   ULONG ulSzBuf);
  243. //-------------------------------------------------------------------------
  244. // This function writes data to a connection.
  245. //
  246. // Input:  hccConnect - handle to the connection
  247. //         pvBuf - points to the buffer containing the data
  248. //         ulSzBuf - specifies the size of the buffer pointed to by pvBuf
  249. // Returns:  COM_ERR_* constant
  250. //-------------------------------------------------------------------------
  251.  
  252. COMERROR EXPENTRY CmnComQueryData(HCCCONNECT hccConnect,PULONG pulData);
  253. //-------------------------------------------------------------------------
  254. // This function returns the size of the data waiting to be read by
  255. // the specified connection.  Since this does not return any data that
  256. // was written by the connection, the number returned does *not* necessarily
  257. // equal the number of bytes in the connection.
  258. //
  259. // Input:  hccConnect - handle to the connection
  260. // Output:  pulData - points to the variable that receives the result
  261. // Returns:  COM_ERR_* constant
  262. //-------------------------------------------------------------------------
  263. #endif                           // #ifdef INCL_CMNCOM
  264.  
  265. #ifdef INCL_CMNDBG
  266. //-------------------------------------------------------------------------
  267. // Debugging routines
  268. //-------------------------------------------------------------------------
  269.  
  270. SHORT EXPENTRY CmnDbgWriteRecord(PVOID pvFile,
  271.                                  USHORT usFileType,
  272.                                  struct _CSLINEDESC *pcFormat,
  273.                                  USHORT usNumRecs,
  274.                                  PBYTE pbBuf);
  275. //-------------------------------------------------------------------------
  276. // This function writes the contents of the specified buffer to the specified
  277. // file.  The format of the buffer is specified in acFormat.
  278. //
  279. // Input:  pvFile - point to the file name or FILE structure
  280. //         usFileType - DWT_TYPE_* constant describing the contents of pvFile
  281. //         pcFormat - points to an array of CSLINEDESC describing the line
  282. //         usNumRecs - specifies the number of CSLINEDESC records are
  283. //                     pointed to by acFormat
  284. //         pbBuf - points to the buffer to print
  285. // Returns:  the number of fields printed is successful, DWT_ERROR otherwise
  286. //-------------------------------------------------------------------------
  287.  
  288. SHORT EXPENTRY CmnDbgWriteText(PVOID pvFile,USHORT usFileType,PCHAR pchFmt,...);
  289. //-------------------------------------------------------------------------
  290. // This function writes debug info to the file described by pvFile.  pvFile
  291. // can be a pointer to a file name or a (FILE *).  In the former case, the
  292. // file is opened upon entry and closed upon exit.
  293. //
  294. // Input:  pvFile - points to the file name or FILE structure
  295. //         usFileType - DWT_TYPE_* constant describing the contents of pvFile
  296. //         pchFmt - point to the format string (as in printf)
  297. // Returns:  number of characters written if successful, DWT_ERROR otherwise
  298. //-------------------------------------------------------------------------
  299.  
  300. SHORT EXPENTRY CmnDbgWriteBinary(PVOID pvFile,
  301.                                  USHORT usFileType,
  302.                                  PVOID pvBuf,
  303.                                  USHORT usSzBuf);
  304. //-------------------------------------------------------------------------
  305. // This function writes the binary data in hexadecimal/ASCII format (a la
  306. // Norton's disk editor) to the specified file.
  307. //
  308. // Input:  pvFile - points to the file name or FILE structure
  309. //         usFileType - DWT_TYPE_* constant describing the contents of pvFile
  310. //         pvBuf - points to the data to be written
  311. //         usSzBuf - specifies the size of the buffer pointed to by pvBuf
  312. // Returns:  number of characters written if successful, DWT_ERROR otherwise
  313. //-------------------------------------------------------------------------
  314. #endif                           // #ifdef INCL_CMNDBG
  315.  
  316. #ifdef INCL_CMNFIL
  317. //-------------------------------------------------------------------------
  318. // File routines
  319. //-------------------------------------------------------------------------
  320.  
  321. BOOL EXPENTRY CmnFilCreateSearch(PCHAR pchMask,
  322.                                  ULONG ulAttr,
  323.                                  PHCFSEARCH phcSearch);
  324. //-------------------------------------------------------------------------
  325. // This function creates a search handle
  326. //
  327. // Input:  pchMask - points to the file mask to search with
  328. //         ulAttr - points to the file attributes to retrieve
  329. // Output:  phcSearch - points to the search handle
  330. // Returns:  TRUE if successful, FALSE otherwise
  331. //-------------------------------------------------------------------------
  332.  
  333. LONG EXPENTRY CmnFilSearchFiles(HCFSEARCH hcSearch,
  334.                                 PCHAR pchBuf,
  335.                                 ULONG ulSzBuf);
  336. //-------------------------------------------------------------------------
  337. // This function searches for the files matching the mask specified in the
  338. // CmnFilCreateSearch call.
  339. //
  340. // Input:  hcSearch - search handle
  341. //         ulSzBuf - contains the size of the buffer pointed to by pchBuf
  342. // Output:  pchBuf - points to the next file that matches the mask
  343. // Returns:  attribute of the file found, FSF_NOFILES if none found, or
  344. //           FSF_ERROR if an error occurred.
  345. //-------------------------------------------------------------------------
  346.  
  347. BOOL EXPENTRY CmnFilDestroySearch(PHCFSEARCH phcSearch);
  348. //-------------------------------------------------------------------------
  349. // This function destroys the specified search handle
  350. //
  351. // Input:  phcSearch - points to the search handle to destroy.
  352. // Output:  phcSearch - points to the value NULL.
  353. // Returns:  TRUE if successful, FALSE otherwise.
  354. //-------------------------------------------------------------------------
  355.  
  356. BOOL EXPENTRY CmnFilQueryExtAttribute(PCHAR pchFile,
  357.                                       PCHAR pchVendor,
  358.                                       PCHAR pchAppl,
  359.                                       PCHAR pchName,
  360.                                       PUSHORT pusAttr,
  361.                                       PBYTE pbValue,
  362.                                       PUSHORT pusSzValue);
  363. //-------------------------------------------------------------------------
  364. // This function queries the value of the specified extended attribute
  365. // from the specified file.  This function cannot be used to query
  366. // EAs of type EAT_MVMT, EAT_MVST, or EAT_ASN1.
  367. //
  368. // Input:  pchFile - points to the name of the file to query
  369. //         pchVendor - points to the name of the company, or is one of
  370. //                     the FEA_* constants.  If an FEA_* constant is
  371. //                     specified, pchAppl and pchName are ignored.
  372. //         pchAppl - points to the name of the application
  373. //         pchName - points to the name of the extended attribute
  374. //         pusAttr - points to the variable which receives the EAT_*
  375. //                   constant for the data
  376. //         pbValue - points to the buffer which receives the data
  377. //         pusSzValue - points to the variable containing the size of the
  378. //                      buffer pointed to by pbValue
  379. // Output:  pusAttr - points to the variable containing the EAT_* type
  380. //          pbValue - points to the extended attribute data
  381. //          pusSzValue - points to the variable containing the size of the
  382. //                       data returned
  383. // Returns:  TRUE if successful, FALSE otherwise
  384. //-------------------------------------------------------------------------
  385.  
  386. BOOL EXPENTRY CmnFilSetExtAttribute(PCHAR pchFile,
  387.                                     USHORT usAttr,
  388.                                     PCHAR pchVendor,
  389.                                     PCHAR pchAppl,
  390.                                     PCHAR pchName,
  391.                                     PBYTE pbValue,
  392.                                     USHORT usSzValue);
  393. //-------------------------------------------------------------------------
  394. // This function adds or changes the specified extended attribute for the
  395. // specified file.  This function cannot be used to set EAs of type
  396. // EAT_MVMT, EAT_MVST, or EAT_ASN1.
  397. //
  398. // Input:  pchFile - points to the name of the file to query
  399. //         usAttr - specifies the EAT_* constant for the data
  400. //         pchVendor - points to the name of the company, or is one of
  401. //                     the FEA_* constants.  If an FEA_* constant is
  402. //                     specified, pchAppl and pchName are ignored.
  403. //         pchAppl - points to the name of the application
  404. //         pchName - points to the name of the extended attribute
  405. //         pbValue - points to the buffer which contains the data
  406. //         usSzValue - specifies the size of the buffer pointed to by
  407. //                     pbValue
  408. // Returns:  TRUE if successful, FALSE otherwise
  409. //-------------------------------------------------------------------------
  410.  
  411. BOOL EXPENTRY CmnFilSplitFilename(PCHAR pchFile,
  412.                                   PCHAR pchDrive,
  413.                                   PCHAR pchPath,
  414.                                   PCHAR pchName);
  415. //-------------------------------------------------------------------------
  416. // This function splits a filename into the drive, path, and name components.
  417. //
  418. // Input:  pchFile - points to the filename to split
  419. // Output:  pchDrive - if not NULL, points to the buffer which receives
  420. //                     the drive portion of the filename
  421. //          pchPath - if not NULL, points to the buffer which receives
  422. //                    the path portion of the filename
  423. //          pchName - if not NULL, points to the buffer which receives
  424. //                    the name portion of the filename
  425. // Returns:  TRUE if successful, FALSE otherwise
  426. //-------------------------------------------------------------------------
  427.  
  428. BOOL EXPENTRY CmnFilFormatDiskette(CHAR chDrive,
  429.                                    PCFFORMATINFO pfiInfo,
  430.                                    PFNDISKIO pfnCallback,
  431.                                    PVOID pvUser);
  432. //-------------------------------------------------------------------------
  433. // This function formats a diskette according to the specified parameters.
  434. //
  435. // For the notification FCD_MSG_WANTFORMATDISK and the type
  436. // FCD_TYPE_PROGESS, pfnCallback should return TRUE for the operation to
  437. // continue or FALSE to halt the operation.
  438. //
  439. // Input:  chDrive - specifies the drive to be formatted.
  440. //         pfiInfo - points to the format parameters.  If NULL, the
  441. //                   drive defaults are used.
  442. //         pfnCallback - pointer to a callback function
  443. //         pvUser - user-data passed to pfnCallback
  444. // Returns:  TRUE if successful, FALSE otherwise.
  445. //-------------------------------------------------------------------------
  446.  
  447. BOOL EXPENTRY CmnFilCopyDiskette(CHAR chSrc,
  448.                                  CHAR chDest,
  449.                                  ULONG ulOptions,
  450.                                  PFNDISKIO pfnCallback,
  451.                                  PVOID pvUser);
  452. //-------------------------------------------------------------------------
  453. // This function copies the contents of one diskette to another.  If the
  454. // destination diskette is already formatted, its capacity must match that
  455. // of the source diskette or this function will fail.
  456. //
  457. // For the notification type FCD_TYPE_PROGRESS and for the following
  458. // FCD_MSG_* notifications, pfnCallback should return TRUE for the operation
  459. // to continue/retry or FALSE to halt/abort the operation.
  460. //
  461. // Input:  chSrc - specifies the source drive
  462. //         chDest - specifies the destination drive
  463. //         ulOptions - specifies one or mor FCD_OPT_* constants
  464. //         pfnCallback - pointer to a callback function
  465. //         pvUser - user-data passed to pfnCallback
  466. // Returns:  TRUE if successful, FALSE otherwise.
  467. //-------------------------------------------------------------------------
  468.  
  469. BOOL EXPENTRY CmnFilQueryLabel(CHAR chDrive,PCHAR pchLabel);
  470. //-------------------------------------------------------------------------
  471. // This function returns the label of the diskette in the drive specified.
  472. //
  473. // Input:  chDrive - specifies the drive to check
  474. //         pchLabel - points to the buffer to copy the label into
  475. // Output:  pchLabel - points to the diskette label
  476. // Returns:  TRUE if successful, FALSE otherwise
  477. //-------------------------------------------------------------------------
  478. #endif                           // #ifdef INCL_CMNFIL
  479.  
  480. #ifdef INCL_CMNLST
  481. //-------------------------------------------------------------------------
  482. // Link-list routines
  483. //-------------------------------------------------------------------------
  484.  
  485. BOOL EXPENTRY CmnLstAddRecord(HCLLIST hclList,
  486.                               PVOID pvRecord,
  487.                               PFNRECCOMP pfnSort,
  488.                               PVOID *ppvResult);
  489. //-------------------------------------------------------------------------
  490. // This function adds a "record" into the linked list in sorted order as
  491. // defined by the user-defined pfnSort function.
  492. //
  493. // Input:  hclList - handle to the list to add the record to
  494. //         pvRecord - points to the record to add
  495. //         pfnSort - points to the comparison function.  If NULL, the function
  496. //                   inserts at the end of the list.  See above for a
  497. //                   description of its parameters.
  498. // Output:  ppvResult - if not NULL on entry, points to the variable pointing
  499. //                      to the new entry
  500. // Returns:  TRUE if successful, FALSE otherwise
  501. //-------------------------------------------------------------------------
  502.  
  503. USHORT EXPENTRY CmnLstAddUniqueRecord(HCLLIST hclList,
  504.                                       PVOID pvRecord,
  505.                                       PFNRECCOMP pfnSearch,
  506.                                       PFNRECCOMP pfnSort,
  507.                                       PVOID *ppvResult);
  508. //-------------------------------------------------------------------------
  509. // This function adds a "record" into the linked list only if the record
  510. // does not already exist.  The record is added in sorted order using the
  511. // pfnSort function.
  512. //
  513. // Input:  hclList - handle to the list to add the record to
  514. //         pvRecord - points to the record to add
  515. //         pfnSearch - points to the search function.  See above for a
  516. //                     description of its parameters.
  517. //         pfnSort - points to the comparison function.  If NULL, the function
  518. //                   inserts at the end of the list.  See above for a
  519. //                   description of its parameters.
  520. // Output:  ppvResult - if not NULL on entry, points to the variable pointing
  521. //                      to the old entry if one already existed or the newly
  522. //                      created entry.
  523. // Returns:  LAUR_NOERROR if successful, LAUR_EXISTS if the record already
  524. //           exists, or LAUR_ERROR otherwise
  525. //-------------------------------------------------------------------------
  526.  
  527. BOOL EXPENTRY CmnLstMoveRecord(HCLLIST hclList,
  528.                                PVOID pvMove,
  529.                                PVOID pvWhere,
  530.                                SHORT sRelative);
  531. //-------------------------------------------------------------------------
  532. // This function moves a record to a position relative to another record in
  533. // the specified list.
  534. //
  535. // Input:  hclList - handle to the list
  536. //         pvMove - pointer to the record to move
  537. //         pvWhere - pointer to the record specifying the new location
  538. //         sRelative - either LQR_PREVIOUS or LQR_NEXT specifying
  539. //                     immediately before or after pvWhere, respectively.
  540. // Returns:  TRUE if successful, FALSE otherwise
  541. //-------------------------------------------------------------------------
  542.  
  543. BOOL EXPENTRY CmnLstCopyList(HCLLIST hclList,
  544.                              HCLLIST hclCopy,
  545.                              PFNRECCOMP pfnSort);
  546. //-------------------------------------------------------------------------
  547. // This function copies one list into another list in sorted order.  Note
  548. // that if a call to CmnLstAddRecord fails, the state of the list being
  549. // modified is undefined.
  550. //
  551. // Input:  hclList - handle to the list to copy into
  552. //         hclCopy - handle to the list to copy from
  553. //         pfnSort - points to the comparison function.  If NULL, the function
  554. //                   will append hclCopy to hclList.  See above for a
  555. //                   description of its parameters.
  556. // Returns:  TRUE if successful, FALSE otherwise
  557. //-------------------------------------------------------------------------
  558.  
  559. BOOL EXPENTRY CmnLstCreateList(USHORT usSzRecord,PHCLLIST phclList);
  560. //-------------------------------------------------------------------------
  561. // This function creates a linked list of records, and initializes it to
  562. // "empty".
  563. //
  564. // Input:  usSzRecord - the size of each record of the linked list
  565. // Output:  phclList - points to the handle to the new list
  566. // Returns:  TRUE if successful, FALSE otherwise
  567. //-------------------------------------------------------------------------
  568.  
  569. BOOL EXPENTRY CmnLstDeleteList(HCLLIST hclList);
  570. //-------------------------------------------------------------------------
  571. // This function deletes the entire list but does not destroy it
  572. //
  573. // Input:  hclList - handle to the list to delete
  574. // Output:  ppvHead - points to the head of the list==NULL
  575. // Returns:  TRUE if successful, FALSE otherwise
  576. //-------------------------------------------------------------------------
  577.  
  578. BOOL EXPENTRY CmnLstDeleteRecord(HCLLIST hclList,PVOID pvRecord);
  579. //-------------------------------------------------------------------------
  580. // This function deletes a record from the linked list.
  581. //
  582. // Input:  hclList - handle to the list to delete the record from
  583. //         pvRecord - points to the record to delete
  584. // Returns:  TRUE if successful, FALSE otherwise
  585. //-------------------------------------------------------------------------
  586.  
  587. BOOL EXPENTRY CmnLstDestroyList(PHCLLIST phclList);
  588. //-------------------------------------------------------------------------
  589. // This function deletes and then destroys the specified list.
  590. //
  591. // Input:  phclList - points to the handle to the list
  592. // Output:  pchList - points to a variable containing NULL
  593. // Returns:  TRUE if successful, FALSE otherwise
  594. //-------------------------------------------------------------------------
  595.  
  596. BOOL EXPENTRY CmnLstPruneList(HCLLIST hclList,
  597.                               PVOID pvRecord,
  598.                               PFNRECCOMP pfnSearch);
  599. //-------------------------------------------------------------------------
  600. // This function deletes records that match the search criteria from the
  601. // specified list.
  602. //
  603. // Input:  hclList - handle to the list to prune
  604. //         pvSearch - points to the application defined search data.  It is
  605. //                    passed to pfnSearch as the second parameter.
  606. //         pfnSearch - points to the comparison function.  See above for a
  607. //                     description of its parameters.
  608. // Returns:  TRUE if successful, FALSE otherwise
  609. //-------------------------------------------------------------------------
  610.  
  611. #define LQR_END                  -1
  612.  
  613. PVOID EXPENTRY CmnLstQueryRecord(HCLLIST hclList,SHORT sNumRecord);
  614. //-------------------------------------------------------------------------
  615. // This function returns the nth record in the specified linked list.
  616. //
  617. // Input:  hclList - handle to the list to query
  618. //         sNumRecord - specifies the 0-based number of the record to
  619. //                      retrieve or a LQR_* constant
  620. // Returns:  pointer to the record if successful, NULL otherwise
  621. //-------------------------------------------------------------------------
  622.  
  623. SHORT EXPENTRY CmnLstQueryRecordCount(HCLLIST hclList);
  624. //-------------------------------------------------------------------------
  625. // This function returns the number of records in the linked list.
  626. //
  627. // Input:  hclList - handle to the list to query
  628. // Returns:  the number of records if successful, LQRC_ERROR otherwise
  629. //-------------------------------------------------------------------------
  630.  
  631. PVOID EXPENTRY CmnLstQueryRelative(PVOID pvRecord,SHORT sWhich);
  632. //-------------------------------------------------------------------------
  633. // This function returns either the previous or next record relative to the
  634. // specified record.
  635. //
  636. // Input:  pvRecord - points to the record to query
  637. //         sNumRecord - specifies either LQR_PREVIOUS or LQR_NEXT
  638. // Returns:  pointer to the record if successfull, or NULL if pvRecord is the
  639. //           head of the list and LQR_PREVIOUS was specified, pvRecord is the
  640. //           tail of the list and LQR_NEXT was specified or an error occurred.
  641. //-------------------------------------------------------------------------
  642.  
  643. BOOL EXPENTRY CmnLstQuickSortList(HCLLIST hclList,
  644.                                   PFNRECMED pfnMedian,
  645.                                   PFNRECCOMP pfnCompare);
  646. //-------------------------------------------------------------------------
  647. // This function sorts the specified list using a version of the quick sort
  648. // algorithm that has been slightly modified to conserve memory.
  649. //
  650. // Input:  hclList - handle to the list to sort
  651. //         pfnMedian - points to a median function.  See above for a
  652. //                     description of its parameters.
  653. //         pfnCompare - points to a comparison function.  See above for a
  654. //                      description of its parameters.
  655. // Output:  hclList - handle to the sorted list
  656. // Returns:  TRUE if successful, FALSE otherwise.
  657. //-------------------------------------------------------------------------
  658.  
  659. PVOID EXPENTRY CmnLstSearchRecord(PVOID pvRecord,
  660.                                   PVOID pvSearch,
  661.                                   PFNRECCOMP pfnSearch);
  662. //-------------------------------------------------------------------------
  663. // This function searches the linked list for a record using the pfnSearch
  664. // function.
  665. //
  666. // Input:  pvRecord - points to the first record of the linked list where
  667. //                    searching is to begin
  668. //         pvSearch - points to the application defined search data.  It is
  669. //                    passed to pfnSearch as the second parameter.
  670. //         pfnSearch - points to the comparison function.  See above for a
  671. //                     description of its parameters.
  672. // Returns:  pointer to record if found, NULL otherwise
  673. //-------------------------------------------------------------------------
  674.  
  675. BOOL EXPENTRY CmnLstSortList(HCLLIST hclList,PFNRECCOMP pfnSort);
  676. //-------------------------------------------------------------------------
  677. // This function performs a bubble sort on the specified list.
  678. //
  679. // Input:  hclList - handle to the list to sort
  680. //         pfnSort - points to the comparison function.  See above for a
  681. //                   description of its parameters.
  682. // Returns:  TRUE if successful, FALSE otherwise.
  683. //-------------------------------------------------------------------------
  684.  
  685. BOOL EXPENTRY CmnLstTraverseList(HCLLIST hclList,PFNRECFUNC pfnFunc);
  686. //-------------------------------------------------------------------------
  687. // This function traverses the specified list, calling the specified function
  688. // for each record in the list.  This can be used, for example, to print
  689. // out each record in the list for debugging purposes.
  690. //
  691. // Input:  hclList - handle to the list to traverse
  692. //         pfnFunc - callback function.  See above for a description of its
  693. //                   parameters.
  694. // Returns:  TRUE if successful, FALSE otherwise
  695. //-------------------------------------------------------------------------
  696. #endif                           // #ifdef INCL_CMNLST
  697.  
  698. #ifdef INCL_CMNMEM
  699. //-------------------------------------------------------------------------
  700. // Memory allocation routines
  701. //-------------------------------------------------------------------------
  702.  
  703. MEMERROR EXPENTRY CmnMemAllocate(HCMMEM hcmMem,ULONG ulSzBuf,PVOID *ppvBuf);
  704. //-------------------------------------------------------------------------
  705. // This function allocates a block of memory from a memory manager instance.
  706. //
  707. // Input:  hcmMem - handle to the memory manager instance.
  708. //         ulSzBuf - specifies the requested size of the memory block.
  709. // Output:  ppvBuf - points to the variable which receives the pointer
  710. //                   to the allocated memory.
  711. // Returns:  MEM_ERR_NOERROR if successful, error code otherwise.
  712. //-------------------------------------------------------------------------
  713.  
  714. MEMERROR EXPENTRY CmnMemFree(HCMMEM hcmMem,PVOID pvBuf);
  715. //-------------------------------------------------------------------------
  716. // This function returns a block of memory to the memory manager.
  717. //
  718. // Input:  hcmMem - handle to the memory manager instance.
  719. //         pvBuf - points to the block of memory to free.
  720. // Returns:  MEM_ERR_NOERROR if successful, error code otherwise
  721. //-------------------------------------------------------------------------
  722.  
  723. MEMERROR EXPENTRY CmnMemInitialize(PCMMEMINFO pcmiInfo,PHCMMEM phcmMem);
  724. //-------------------------------------------------------------------------
  725. // This function creates an instance of the memory manager.
  726. //
  727. // Input:  pcmiInfo - points to a CMMEMINFO structure which specifies the
  728. //                    desired attributes of the instance.  If NULL, the
  729. //                    defaults are used.
  730. // Output:  phcmMem - points to the variable containing the memory handle.
  731. // Returns:  MEM_ERR_NOERROR if successful, error code otherwise.
  732. //-------------------------------------------------------------------------
  733.  
  734. ULONG EXPENTRY CmnMemQueryMemSize(PVOID pvBuf);
  735. //-------------------------------------------------------------------------
  736. // This function returns the size of a block of memory.  No validation is
  737. // done to determine whether or not the memory was allocated with
  738. // CmnMemAllocate.
  739. //
  740. // Input:  pvBuf - points to the block of memory to query.
  741. // Returns:  MEM_ERR_NOERROR if successful, error code otherwise
  742. //-------------------------------------------------------------------------
  743.  
  744. MEMERROR EXPENTRY CmnMemReset(HCMMEM hcmMem);
  745. //-------------------------------------------------------------------------
  746. // This function deallocates *all* memory associated with a memory manager
  747. // instance and resets the heaps to "empty."
  748. //
  749. // Input:  hcmMem - handle to the memory manager instance.
  750. // Returns:  MEM_ERR_NOERROR if successful, error code otherwise
  751. //-------------------------------------------------------------------------
  752.  
  753. MEMERROR EXPENTRY CmnMemTerminate(PHCMMEM phcmMem);
  754. //-------------------------------------------------------------------------
  755. // This function destroys an instance of the memory manager.
  756. //
  757. // Input:  phcmMem - points to the variable containing the memory handle
  758. //                   to destroy.
  759. // Output:  phcmMem - points to the value NULL.
  760. // Returns:  MEM_ERR_NOERROR if successful, error code otherwise.
  761. //-------------------------------------------------------------------------
  762. #endif                           // #ifdef INCL_CMNMEM
  763.  
  764. #ifdef INCL_CMNOBJ
  765. //-------------------------------------------------------------------------
  766. // Object routines
  767. //-------------------------------------------------------------------------
  768.  
  769. OBJERROR EXPENTRY CmnObjInitialize(PCOROOTINFO pcoriInfo,PHCOOBJECT phcoRoot);
  770. //-------------------------------------------------------------------------
  771. // This function initializes the object manager and returns the handle
  772. // to the root object.
  773. //
  774. // Input:  pcoriInfo - points to the COROOTINFO structure containing
  775. //                     the desired characteristics of the instance
  776. // Output:  phcoRoot - points to the variable that received the created
  777. //                     root object handle
  778. // Returns:  OBJ_ERR_NOERROR if successful, error code otherwise
  779. //-------------------------------------------------------------------------
  780.  
  781. OBJERROR EXPENTRY CmnObjTerminate(PHCOOBJECT phcoRoot);
  782. //-------------------------------------------------------------------------
  783. // This function destroys all children of the specified root object
  784. // (via a call to CmnObjReset()) and terminates the object manager
  785. // instance.
  786. //
  787. // Input:  phcoRoot - points to the variable specified the root object
  788. //                    handle.  On return, this variable contains NULL.
  789. // Returns:  OBJ_ERR_NOERROR if successful, error code otherwise
  790. //-------------------------------------------------------------------------
  791.  
  792. OBJERROR EXPENTRY CmnObjReset(HCOOBJECT hcoRoot);
  793. //-------------------------------------------------------------------------
  794. // This function deletes all child objects from the specified root object.
  795. //
  796. // Input:  hcoRoot - handle of the root object
  797. // Returns:  OBJ_ERR_NOERROR if successful, error code otherwise
  798. //-------------------------------------------------------------------------
  799.  
  800. OBJERROR EXPENTRY CmnObjQueryObject(HCOOBJECT hcoObject,
  801.                                     SHORT sQuery,
  802.                                     PHCOOBJECT phcoResult);
  803. //-------------------------------------------------------------------------
  804. // This function returns the handle of the object related to the specified
  805. // object in the specified way.
  806. //
  807. // Input:  hcoObject - handle to the object to query the relationship of
  808. //         sQuery - an OQO_* constant specifying the relationship
  809. // Output:  phcoResult - points to the variable which receives the result
  810. // Returns:  OBJ_ERR_NOERROR if successful, error code otherwise
  811. //-------------------------------------------------------------------------
  812.  
  813. OBJERROR EXPENTRY CmnObjCreateObject(HCOOBJECT hcoParent,
  814.                                      PCHAR pchName,
  815.                                      PHCOOBJECT phcoResult);
  816. //-------------------------------------------------------------------------
  817. // This function creates a new object whose parent is specified in
  818. // hcoParent.
  819. //
  820. // Input:  hcoParent - handle to the parent object
  821. //         pchName - points to the variable specifying the subname.  This
  822. //                   cannot contain a backslash
  823. // Output:  phcoResult - points to the variable which receives the handle
  824. //                       to the newly created object
  825. // Returns:  OBJ_ERR_NOERROR if successful, error code otherwise
  826. //-------------------------------------------------------------------------
  827.  
  828. OBJERROR EXPENTRY CmnObjDestroyObject(PHCOOBJECT phcoObject);
  829. //-------------------------------------------------------------------------
  830. // This function destroys the specified object.  It is an error to call
  831. // this function with the root object handle.
  832. //
  833. // Input:  phcoObject - points to the variable specifying the handle of
  834. //                      the object to destroy.  On return, this variable
  835. //                      contains NULL.
  836. // Returns:  OBJ_ERR_NOERROR if successful, error code otherwise
  837. //-------------------------------------------------------------------------
  838.  
  839. OBJERROR EXPENTRY CmnObjSetObjectData(HCOOBJECT hcoObject,
  840.                                       PVOID pvBuffer,
  841.                                       ULONG ulSzBuf);
  842. //-------------------------------------------------------------------------
  843. // This function sets the object-specific data.  Any data that was
  844. // previously set into the object is disposed of an the memory is returned
  845. // to the system.
  846. //
  847. // Intput:  hcoObject - handle to the object
  848. //          pvBuffer - points to the new object data
  849. //          ulSzBuf - specifies the size of the buffer pointed to by
  850. //                    pvBuffer
  851. // Returns:  OBJ_ERR_NOERROR if successful, error code otherwise
  852. //-------------------------------------------------------------------------
  853.  
  854. OBJERROR EXPENTRY CmnObjQueryObjectData(HCOOBJECT hcoObject,
  855.                                         PVOID pvBuffer,
  856.                                         PULONG pulSzBuf);
  857. //-------------------------------------------------------------------------
  858. // This function returns the object-specific data set by CmnObjSetData().
  859. //
  860. // Intput:  hcoObject - handle to the object
  861. // Output:  pvBuffer - points to the receiving buffer.  If NULL, pulSzBuf
  862. //                     contains the size required to completely hold the
  863. //                     data
  864. //          pulSzBuf - points to the variable that receives the number of
  865. //                     of bytes copied if pvBuffer!=NULL.  If pvBuffer==NULL,
  866. //                     the variable instead contains the size in bytes of
  867. //                     the data
  868. // Returns:  OBJ_ERR_NOERROR if successful, error code otherwise
  869. //-------------------------------------------------------------------------
  870.  
  871. OBJERROR EXPENTRY CmnObjObjectFromName(HCOOBJECT hcoObject,
  872.                                        PCHAR pchName,
  873.                                        PHCOOBJECT phcoResult);
  874. //-------------------------------------------------------------------------
  875. // This function returns the object with the given relative or absolute
  876. // name.  The name to search for consists of one or more subnames separated
  877. // by backslashes.  If the name begins with a backslash, searching begins
  878. // at the root object.  As with filenames, the subnames "." and ".." have
  879. // special meanings analagous to the file system interpretations.
  880. //
  881. // Input:  hcoObject - handle to the object
  882. //         pchName - points to the name
  883. // Output:  phcoResult - points to the variable which receives the result
  884. // Returns:  OBJ_ERR_NOERROR if successful, error code otherwise
  885. //-------------------------------------------------------------------------
  886. #endif                           // #ifdef INCL_CMNOBJ
  887.  
  888. #ifdef INCL_CMNSET
  889. //-------------------------------------------------------------------------
  890. // Set routines
  891. //-------------------------------------------------------------------------
  892.  
  893. BOOL EXPENTRY CmnSetCreateSet(ULONG ulMaxElems,PHCSSET phcsSet);
  894. //-------------------------------------------------------------------------
  895. // This function creates a set with the specified number of elements.
  896. //
  897. // Input:  ulMaxElems - specifies the maximum number of elements.
  898. // Output:  phcsSet - points to the variable containing the set handle
  899. // Returns:  TRUE if successful, FALSE otherwise
  900. //-------------------------------------------------------------------------
  901.  
  902. BOOL EXPENTRY CmnSetDestroySet(PHCSSET phcsSet);
  903. //-------------------------------------------------------------------------
  904. // This function destroys the set handle pointed to by phcsSet.
  905. //
  906. // Input:  phcsSet - points to the variable specifying the set handle to
  907. //                  destroy
  908. // Returns:  TRUE if successful, FALSE otherwise
  909. //-------------------------------------------------------------------------
  910.  
  911. BOOL EXPENTRY CmnSetSetElement(HCSSET hcsSet,ULONG ulElement);
  912. //-------------------------------------------------------------------------
  913. // This function sets the specified element in the specified set.
  914. //
  915. // Input:  hcsSet - specifies the set handle
  916. //         ulElement - specifies the element to set
  917. // Returns:  TRUE if successful, FALSE otherwise
  918. //-------------------------------------------------------------------------
  919.  
  920. BOOL EXPENTRY CmnSetClearElement(HCSSET hcsSet,ULONG ulElement);
  921. //-------------------------------------------------------------------------
  922. // This function clears the specified element in the specified set.
  923. //
  924. // Input:  hcsSet - specifies the set handle
  925. //         ulElement - specifies the element to clear
  926. // Returns:  TRUE if successful, FALSE otherwise
  927. //-------------------------------------------------------------------------
  928.  
  929. BOOL EXPENTRY CmnSetInvertElement(HCSSET hcsSet,ULONG ulElement);
  930. //-------------------------------------------------------------------------
  931. // This function inverts the state of the specified element.
  932. //
  933. // Input:  hcsSet - specifies the set handle
  934. //         ulElement - specifies the element to invert
  935. // Returns:  TRUE if successful, FALSE otherwise
  936. //-------------------------------------------------------------------------
  937.  
  938. LONG EXPENTRY CmnSetFindElement(HCSSET hcsSet,ULONG ulNumber,USHORT usType);
  939. //-------------------------------------------------------------------------
  940. // This function finds the nth element that is either set or clear.
  941. //
  942. // Input:  hcsSet - specifies the set handle
  943. //         ulNumber - specifies the number of the element desired
  944. //         usType - specifies either SFE_SET if the nth element set is
  945. //                  desired or SFE_CLEAR if the nth element clear is
  946. //                  desired
  947. // Returns:  Element number if found, SFE_NOTFOUND if not found, or
  948. //           SFE_ERROR if an error occurred
  949. //-------------------------------------------------------------------------
  950.  
  951. BOOL EXPENTRY CmnSetSetSet(HCSSET hcsSet);
  952. //-------------------------------------------------------------------------
  953. // This function sets all of the elements of the specified set.
  954. //
  955. // Input:  hcsSet - specifies the set handle
  956. // Returns:  TRUE if successful, FALSE otherwise
  957. //-------------------------------------------------------------------------
  958.  
  959. BOOL EXPENTRY CmnSetClearSet(HCSSET hcsSet);
  960. //-------------------------------------------------------------------------
  961. // This function clears all of the elements of the specified set.
  962. //
  963. // Input:  hcsSet - specifies the set handle
  964. // Returns:  TRUE if successful, FALSE otherwise
  965. //-------------------------------------------------------------------------
  966.  
  967. BOOL EXPENTRY CmnSetInvertSet(HCSSET hcsSet);
  968. //-------------------------------------------------------------------------
  969. // This function inverts all of the elements of the specified set.
  970. //
  971. // Input:  hcsSet - specifies the set handle
  972. // Returns:  TRUE if successful, FALSE otherwise
  973. //-------------------------------------------------------------------------
  974.  
  975. SHORT EXPENTRY CmnSetQueryElement(HCSSET hcsSet,ULONG ulElement);
  976. //-------------------------------------------------------------------------
  977. // This function returns the state of the specified element.
  978. //
  979. // Input:  hcsSet - specifies the set handle
  980. //         ulElement - specifies the element to query
  981. // Returns:  SQE_SET if the element is set, SQE_CLEAR if the element is not
  982. //           set, or SQE_ERROR if an error occurs
  983. //-------------------------------------------------------------------------
  984.  
  985. SHORT EXPENTRY CmnSetQueryEqualSets(HCSSET hcsSet1,HCSSET hcsSet2);
  986. //-------------------------------------------------------------------------
  987. // This function compares two sets for equality.
  988. //
  989. // Input:  hcsSet1 - specifies the first set handle
  990. //         hcsSet2 - specifies the second set handle
  991. // Returns:  SQES_EQUAL if the sets are equal, SQES_NOTEQUAL if the sets
  992. //           are not equal, or SQES_ERROR if an error occurs
  993. //-------------------------------------------------------------------------
  994.  
  995. HCSSET EXPENTRY CmnSetCombineSets(HCSSET hcsSet1,HCSSET hcsSet2);
  996. //-------------------------------------------------------------------------
  997. // This function calculates the union of the specified sets and returns
  998. // the result.
  999. //
  1000. // Input:  hcsSet1 - specifies the first set handle
  1001. //         hcsSet2 - specifies the second set handle
  1002. // Returns:  a new set handle containing the union if successful, NULL
  1003. //           otherwise
  1004. //-------------------------------------------------------------------------
  1005.  
  1006. HCSSET EXPENTRY CmnSetIntersectSets(HCSSET hcsSet1,HCSSET hcsSet2);
  1007. //-------------------------------------------------------------------------
  1008. // This function calculates the intersection of the specified sets and returns
  1009. // the result.  If the sets are not equal in size, the function pads the
  1010. // smaller set with "set" elements.
  1011. //
  1012. // Input:  hcsSet1 - specifies the first set handle
  1013. //         hcsSet2 - specifies the second set handle
  1014. // Returns:  a new set handle containing the intersection if successful,
  1015. //           NULL otherwise
  1016. //-------------------------------------------------------------------------
  1017. #endif                           // #ifdef INCL_CMNSET
  1018.  
  1019. #ifdef INCL_CMNSIG
  1020. //-------------------------------------------------------------------------
  1021. // Signal routines
  1022. //-------------------------------------------------------------------------
  1023.  
  1024. BOOL EXPENTRY CmnSigCreateSignalList(PHCSSIGNALLIST phcsList);
  1025. //-------------------------------------------------------------------------
  1026. // This function creates a signal list which is used in subsequent calls to
  1027. // the CmnSig functions.  Typically, only one per application is needed,
  1028. // although this might not always be true.
  1029. //
  1030. // Output:  phcsList - points to the variable specifying the list handle
  1031. // Returns:  TRUE if successful, FALSE otherwise
  1032. //-------------------------------------------------------------------------
  1033.  
  1034. BOOL EXPENTRY CmnSigDestroySignalList(PHCSSIGNALLIST phcsList);
  1035. //-------------------------------------------------------------------------
  1036. // This function destroys the specified signal list.
  1037. //
  1038. // Input:  phcsList - points to the variable specifying the list handle
  1039. // Output:  phcsList - points to the variable specifying NULL
  1040. // Returns:  TRUE if successful, FALSE otherwise
  1041. //-------------------------------------------------------------------------
  1042.  
  1043. BOOL EXPENTRY CmnSigCreateSignal(HCSSIGNALLIST hcsList,
  1044.                                  ULONG ulId,
  1045.                                  PHCSSIGNAL phcSignal);
  1046. //-------------------------------------------------------------------------
  1047. // This function creates a signal handle in the specified signal list.
  1048. // The returned signal handle is used in subsequent calls to the signal
  1049. // functions.  Note that ulId can be any id unique to the list.
  1050. //
  1051. // Input:  hcsList - specifies the list handle to add the signal to
  1052. //         ulId - specifies the id of the handle to be created
  1053. // Output:  phcSignal - points to the variable containing the created
  1054. //                      signal handle
  1055. // Returns:  TRUE if successful, FALSE otherwise
  1056. //-------------------------------------------------------------------------
  1057.  
  1058. BOOL EXPENTRY CmnSigDestroySignal(PHCSSIGNAL phcSignal);
  1059. //-------------------------------------------------------------------------
  1060. // This function destroys the specified signal from the owner list.
  1061. //
  1062. // Input:  phcSignal - points to the variable specifying the signal handle
  1063. //                     to delete
  1064. // Output:  phcSignal - points to the variable specifying NULL
  1065. // Returns:  TRUE if successful, FALSE otherwise
  1066. //-------------------------------------------------------------------------
  1067.  
  1068. BOOL EXPENTRY CmnSigQuerySignal(HCSSIGNALLIST hcsList,
  1069.                                 ULONG ulId,
  1070.                                 PHCSSIGNAL phcSignal);
  1071. //-------------------------------------------------------------------------
  1072. // This function searches the specified list for the signal handle with the
  1073. // specified id.
  1074. //
  1075. // Input:  hcsList - specifies the list to search
  1076. //         ulId - specifies the signal id to search for
  1077. // Output:  phcSignal - points to the variable specifying the signal handle
  1078. //                      if found, NULL otherwise
  1079. // Returns:  TRUE if successful, FALSE otherwise
  1080. //-------------------------------------------------------------------------
  1081.  
  1082. BOOL EXPENTRY CmnSigSetSignalValue(HCSSIGNAL hcSignal,ULONG ulSignal);
  1083. //-------------------------------------------------------------------------
  1084. // This function sets the signal value for the specified signal handle to
  1085. // the specified value.  This is useful for unique signal values.  Note
  1086. // that since 0 could possibly be a valid signal value, you must call
  1087. // CmnSigSetSignalValue() with the "empty" value (this is application-specific)
  1088. // to clear this value.
  1089. //
  1090. // For signal values whose individual bits have specific interpretations,
  1091. // use CmnSigSetSignalBit().
  1092. //
  1093. // Input:  hcSignal - specifies the signal handle to set
  1094. //         ulSignal - specifies the new signal value
  1095. // Returns:  TRUE if successful, FALSE otherwise
  1096. //-------------------------------------------------------------------------
  1097.  
  1098. BOOL EXPENTRY CmnSigSetSignalBit(HCSSIGNAL hcSignal,ULONG ulSignal);
  1099. //-------------------------------------------------------------------------
  1100. // This function sets the specified signal value bits for the specified
  1101. // signal handle.
  1102. //
  1103. // Input:  hcSignal - specifies the signal handle to set
  1104. //         ulSignal - specifies the signal bits to set
  1105. // Returns:  TRUE if successful, FALSE otherwise
  1106. //-------------------------------------------------------------------------
  1107.  
  1108. BOOL EXPENTRY CmnSigClearSignalBit(HCSSIGNAL hcSignal,ULONG ulSignal);
  1109. //-------------------------------------------------------------------------
  1110. // This function clears the specified signal value bits for the specified
  1111. // signal handle.
  1112. //
  1113. // Input:  hcSignal - specifies the signal handle to clear
  1114. //         ulSignal - specifies the signal bits to clear
  1115. // Returns:  TRUE if successful, FALSE otherwise
  1116. //-------------------------------------------------------------------------
  1117.  
  1118. BOOL EXPENTRY CmnSigSetAllSignalValues(HCSSIGNALLIST hcsList,ULONG ulSignal);
  1119. //-------------------------------------------------------------------------
  1120. // This function sets all of the signals in the specified list to a specific
  1121. // value.
  1122. //
  1123. // Input:  hcsList - specifies the list to set
  1124. //         ulSignal - specifies the new value of the list
  1125. // Returns:  TRUE if successful, FALSE otherwise
  1126. //-------------------------------------------------------------------------
  1127.  
  1128. BOOL EXPENTRY CmnSigSetAllSignalBits(HCSSIGNALLIST hcsList,ULONG ulSignal);
  1129. //-------------------------------------------------------------------------
  1130. // This function sets the specified bits of all of the signals in the
  1131. // specified list.
  1132. //
  1133. // Input:  hcsList - specifies the list to set
  1134. //         ulSignal - specifies the new value of the list
  1135. // Returns:  TRUE if successful, FALSE otherwise
  1136. //-------------------------------------------------------------------------
  1137.  
  1138. BOOL EXPENTRY CmnSigClearAllSignalBits(HCSSIGNALLIST hcsList,ULONG ulSignal);
  1139. //-------------------------------------------------------------------------
  1140. // This function clears the specified bits of all of the signals in the
  1141. // specified list.
  1142. //
  1143. // Input:  hcsList - specifies the list to set
  1144. //         ulSignal - specifies the new value of the list
  1145. // Returns:  TRUE if successful, FALSE otherwise
  1146. //-------------------------------------------------------------------------
  1147.  
  1148. BOOL EXPENTRY CmnSigQuerySignalId(HCSSIGNAL hcSignal,PULONG pulId);
  1149. //-------------------------------------------------------------------------
  1150. // This function returns the id of the specified signal handle.
  1151. //
  1152. // Input:  hcSignal - specifies the signal handle to query
  1153. // Output:  pulId - points the variable specifying the signal id
  1154. // Returns:  TRUE if successful, FALSE otherwise
  1155. //-------------------------------------------------------------------------
  1156.  
  1157. BOOL EXPENTRY CmnSigQuerySignalValue(HCSSIGNAL hcSignal,PULONG pulSignal);
  1158. //-------------------------------------------------------------------------
  1159. // This function returns the current signal value for the specified signal.
  1160. //
  1161. // Input:  hcSignal - specifies the signal handle to query
  1162. // Output:  pulSignal - points the variable specifying the signal value
  1163. // Returns:  TRUE if successful, FALSE otherwise
  1164. //-------------------------------------------------------------------------
  1165.  
  1166. USHORT EXPENTRY CmnSigWaitSignalValue(HCSSIGNAL hcSignal,
  1167.                                       ULONG ulSignal,
  1168.                                       LONG lTimeout);
  1169. //-------------------------------------------------------------------------
  1170. // This function waits for a signal handle's signal value to equal a
  1171. // specified value, subject to a timeout.
  1172. //
  1173. // Input:  hcSignal - specifies the signal handle to wait for
  1174. //         ulSignal - specifies the signal value to wait for
  1175. //         lTimeout - specifies the timeout in milliseconds, or an
  1176. //                    SWS_TIMEOUT_* value
  1177. // Returns:  SWS_RC_SIGNALSET if the signal was set, SWS_RC_TIMEOUT if
  1178. //           a timeout occurred, or SWS_RC_ERROR if an error occurred
  1179. //-------------------------------------------------------------------------
  1180.  
  1181. USHORT EXPENTRY CmnSigWaitSignalBit(HCSSIGNAL hcSignal,
  1182.                                     ULONG ulSignal,
  1183.                                     LONG lTimeout);
  1184. //-------------------------------------------------------------------------
  1185. // This function waits for a signal handle's signal value to have a
  1186. // specific set of bits set, subject to a timeout.
  1187. //
  1188. // Note that this is different than CmnSigWaitSignal() in that the other
  1189. // bits can be any value, whereas the said function checks for equality
  1190. // for *all* bits.
  1191. //
  1192. // Input:  hcSignal - specifies the signal handle to wait for
  1193. //         ulSignal - specifies the signal value bits to wait for
  1194. //         lTimeout - specifies the timeout in milliseconds, or an
  1195. //                    SWS_TIMEOUT_* value
  1196. // Returns:  SWS_RC_SIGNALSET if the signal was set, SWS_RC_TIMEOUT if
  1197. //           a timeout occurred, or SWS_RC_ERROR if an error occurred
  1198. //-------------------------------------------------------------------------
  1199.  
  1200. USHORT EXPENTRY CmnSigWaitAllSignalValues(HCSSIGNALLIST hcsList,
  1201.                                           ULONG ulSignal,
  1202.                                           LONG lTimeout);
  1203. //-------------------------------------------------------------------------
  1204. // This function waits for *all* signal handles in the specified list to have
  1205. // the signal value specified, subject to a timeout.
  1206. //
  1207. // Input:  hcsList - specifies the signal list to wait for
  1208. //         ulSignal - specifies the signal value to wait for
  1209. //         lTimeout - specifies the timeout in milliseconds, or an
  1210. //                    SWS_TIMEOUT_* value
  1211. // Returns:  SWS_RC_SIGNALSET if the signal was set, SWS_RC_TIMEOUT if
  1212. //           a timeout occurred, or SWS_RC_ERROR if an error occurred
  1213. //-------------------------------------------------------------------------
  1214.  
  1215. USHORT EXPENTRY CmnSigWaitAllSignalBits(HCSSIGNALLIST hcsList,
  1216.                                         ULONG ulSignal,
  1217.                                         LONG lTimeout);
  1218. //-------------------------------------------------------------------------
  1219. // This function waits for *all* signal handles in the specified list to have
  1220. // the set of signal value bits set, subject to a timeout.
  1221. //
  1222. // Note that this is different than CmnSigWaitSignal() in that the other
  1223. // bits can be any value, whereas the said function checks for equality
  1224. // for *all* bits.
  1225. //
  1226. // Input:  hcsList - specifies the signal list to wait for
  1227. //         ulSignal - specifies the signal value to wait for
  1228. //         lTimeout - specifies the timeout in milliseconds, or an
  1229. //                    SWS_TIMEOUT_* value
  1230. // Returns:  SWS_RC_SIGNALSET if the signal was set, SWS_RC_TIMEOUT if
  1231. //           a timeout occurred, or SWS_RC_ERROR if an error occurred
  1232. //-------------------------------------------------------------------------
  1233. #endif                           // #ifdef INCL_CMNSIG
  1234.  
  1235. #ifdef INCL_CMNSPR
  1236. SPRERROR EXPENTRY CmnSprCreatePlayground(HAB habAnchor,
  1237.                                          PHCSPLAYGROUND phpgPlay);
  1238. //-------------------------------------------------------------------------
  1239. // This function creates a playground to which sprites can be added.
  1240. //
  1241. // Input:  habAnchor - anchor block of the calling thread.
  1242. // Output:  phpgPlay - points to the variable with the HCSPLAYGROUND handle
  1243. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1244. //-------------------------------------------------------------------------
  1245.  
  1246. SPRERROR EXPENTRY CmnSprDestroyPlayground(HCSPLAYGROUND hpgPlay);
  1247. //-------------------------------------------------------------------------
  1248. // This function destroys the playground including any sprites that are
  1249. // still members of it.  All resources consumed by the playground,
  1250. // including the back bitmap, are returned to the system.
  1251. //
  1252. // Input:  hpgPlay - handle to the playground
  1253. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1254. //-------------------------------------------------------------------------
  1255.  
  1256. SPRERROR EXPENTRY CmnSprAddSprite(HCSPLAYGROUND hpgPlay,HCSSPRITE hsSprite);
  1257. //-------------------------------------------------------------------------
  1258. // This function labels a sprite as a "member" of the specified playground.
  1259. // Doing so allows the application to control the sprite's position,
  1260. // visibility, etc. on a drawing surface.
  1261. //
  1262. // Input:  hpgPlay - handle to the playground
  1263. //         hsSprite - handle to the sprite to add
  1264. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1265. //-------------------------------------------------------------------------
  1266.  
  1267. SPRERROR EXPENTRY CmnSprRemoveSprite(HCSPLAYGROUND hpgPlay,HCSSPRITE hsSprite);
  1268. //-------------------------------------------------------------------------
  1269. // This function removes the sprite from the membership list of the
  1270. // specified playground.  The sprite can then be added to another
  1271. // playground, or this one at a later time.
  1272. //
  1273. // Since there is a limited number of sprites that can be members of
  1274. // a playground, this function can be used to temporarily remove unused
  1275. // sprites from a playground so that others can be used.
  1276. //
  1277. // Input:  hpgPlay - handle to the playground
  1278. //         hsSprite - handle to the sprite to remove
  1279. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1280. //-------------------------------------------------------------------------
  1281.  
  1282. SPRERROR EXPENTRY CmnSprSetPlaygroundBack(HCSPLAYGROUND hpgPlay,
  1283.                                           HBITMAP hbmNew,
  1284.                                           HBITMAP *phbmOld);
  1285. //-------------------------------------------------------------------------
  1286. // This function sets the background bitmap of the playground.
  1287. //
  1288. // Note that, once this function is called, the bitmap is managed by
  1289. // the sprite subsystem.  The bitmap should *NOT* be deleted by the
  1290. // application unless the bitmap is "unset" from the playground (by
  1291. // calling this function again with a different handle).
  1292. //
  1293. // Input:  hpgPlay - handle to the playground
  1294. //         hbmNew - handle to the new bitmap to used as the background
  1295. // Output:  phbmOld - points to the handle to the old background bitmap.
  1296. //          This can be NULL, meaning that the application isn't interested
  1297. //          in receiving this value.
  1298. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1299. //-------------------------------------------------------------------------
  1300.  
  1301. SPRERROR EXPENTRY CmnSprQueryPlaygroundBack(HCSPLAYGROUND hpgPlay,
  1302.                                             HBITMAP *phbmBack);
  1303. //-------------------------------------------------------------------------
  1304. // This function returns the handle of the background bitmap currently in
  1305. // use.
  1306. //
  1307. // Input:  hpgPlay - handle to the playground
  1308. // Output:  phbmBack - points to the handle to the background bitmap.
  1309. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1310. //-------------------------------------------------------------------------
  1311.  
  1312. SPRERROR EXPENTRY CmnSprSetPlaygroundSize(HCSPLAYGROUND hpgPlay,
  1313.                                           PSIZEL pszlSize);
  1314. //-------------------------------------------------------------------------
  1315. // This function sets the playground size for playgrounds that do not have
  1316. // a bitmap set as the background.
  1317. //
  1318. // Input:  hpgPlay - handle to the playground
  1319. //         pszlSize - points to the size of the playground
  1320. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1321. //-------------------------------------------------------------------------
  1322.  
  1323. SPRERROR EXPENTRY CmnSprQueryPlaygroundSize(HCSPLAYGROUND hpgPlay,
  1324.                                             PSIZEL pszlSize);
  1325. //-------------------------------------------------------------------------
  1326. // This function returns the size of the playground.  For playgrounds with
  1327. // bitmaps set as the background, the returned value is the size of the
  1328. // bitmap.  Otherwise, the returned value is that which was specified on
  1329. // the last call to CmnSprSetPlaygroundSize().
  1330. //
  1331. // Input:  hpgPlay - handle to the playground
  1332. //         pszlSize - points to the variable to receive the size of the
  1333. //                    playground
  1334. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1335. //-------------------------------------------------------------------------
  1336.  
  1337. SPRERROR EXPENTRY CmnSprSetPlaygroundColor(HCSPLAYGROUND hpgPlay,
  1338.                                            LONG lBackColor);
  1339. //-------------------------------------------------------------------------
  1340. // This function sets the new background color of the playground and is
  1341. // only valid if the playground doesn't have a bitmap.
  1342. //
  1343. // Input:  hpgPlay - handle to the playground
  1344. //         lBackColor - specifies the new background color
  1345. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1346. //-------------------------------------------------------------------------
  1347.  
  1348. SPRERROR EXPENTRY CmnSprQueryPlaygroundColor(HCSPLAYGROUND hpgPlay,
  1349.                                              PLONG plBackColor);
  1350. //-------------------------------------------------------------------------
  1351. // This function redraws the playground and all sprites belonging to the
  1352. // playground.
  1353. //
  1354. // Input:  hpsDraw - handle to the HPS to draw the playground in
  1355. //         hpgPlay - handle to the playground
  1356. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1357. //-------------------------------------------------------------------------
  1358.  
  1359. SPRERROR EXPENTRY CmnSprSetUpdateFlag(HCSPLAYGROUND hpgPlay,BOOL bUpdate);
  1360. //-------------------------------------------------------------------------
  1361. // This function sets the update flag for the playground.  If FALSE, no
  1362. // drawing actually takes place in any of the functions requiring an HPS,
  1363. // and the value of the HPS handle may be NULLHANDLE.  If TRUE, updating
  1364. // is reenabled, but you should still call CmnSprDrawPlayground() to refresh
  1365. // the screen with the current contents.
  1366. //
  1367. // Input:  hpgPlay - handle to the playground
  1368. //         bUpdate - specifies the new update flag
  1369. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1370. //-------------------------------------------------------------------------
  1371.  
  1372. SPRERROR EXPENTRY CmnSprQueryUpdateFlag(HCSPLAYGROUND hpgPlay,PBOOL pbUpdate);
  1373. //-------------------------------------------------------------------------
  1374. // This function returns the setting of the update flag.  See the notes
  1375. // for CmnSprSetUpdateFlag() for more information about this setting.
  1376. //
  1377. // Input:  hpgPlay - handle to the playground
  1378. //         pbUpdate - points to the variable to receive the update flag
  1379. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1380. //-------------------------------------------------------------------------
  1381.  
  1382. SPRERROR EXPENTRY CmnSprDrawPlayground(HPS hpsDraw,HCSPLAYGROUND hpgPlay);
  1383. //-------------------------------------------------------------------------
  1384. // This function redraws the playground and all sprites belonging to the
  1385. // playground.
  1386. //
  1387. // Input:  hpsDraw - handle to the HPS to draw the playground in
  1388. //         hpgPlay - handle to the playground
  1389. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1390. //-------------------------------------------------------------------------
  1391.  
  1392. SPRERROR EXPENTRY CmnSprCreateSprite(HAB habAnchor,
  1393.                                      HBITMAP hbmBitmap,
  1394.                                      PHCSSPRITE phsSprite);
  1395. //-------------------------------------------------------------------------
  1396. // This function creates a sprite from the specified bitmap.  The sprite
  1397. // cannot be moved, shown, etc., however, until it is associated with a
  1398. // playground.
  1399. //
  1400. // The color black is used as the transparency color.  If you need to use
  1401. // black in the bitmap without it becoming transparent, use the next
  1402. // closest color.  <grin>
  1403. //
  1404. // New sprites are initialized as being at position (0,0) and hidden.
  1405. //
  1406. // Note that, once this function is called, the bitmap is managed by
  1407. // the sprite subsystem.  The bitmap should *NOT* be deleted by the
  1408. // application or else unpredictable results will occur.
  1409. //
  1410. // Input:  habAnchor - anchor block of the calling thread.
  1411. //         hbmBitmap - handle to the bitmap
  1412. // Output:  phsSprite - points to the sprite handle
  1413. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1414. //-------------------------------------------------------------------------
  1415.  
  1416. SPRERROR EXPENTRY CmnSprDestroySprite(HCSSPRITE hsSprite);
  1417. //-------------------------------------------------------------------------
  1418. // This function destroys the sprite and returns all resources to the
  1419. // system.
  1420. //
  1421. // Input:  hsSprite - handle to the sprite
  1422. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1423. //-------------------------------------------------------------------------
  1424.  
  1425. SPRERROR EXPENTRY CmnSprSetSpritePosition(HPS hpsDraw,
  1426.                                           HCSSPRITE hsSprite,
  1427.                                           PPOINTL pptlNew);
  1428. //-------------------------------------------------------------------------
  1429. // This function changes the position of the sprite.  This function is
  1430. // optimized so that, if the rectangle bounding the sprite at the new
  1431. // position overlaps the old, only one "bit blit" to the specified HPS
  1432. // is done, eliminating flicker.
  1433. //
  1434. // Input:  hpsDraw - handle to the HPS to draw the sprite in once it is
  1435. //                   moved
  1436. //         hsSprite - handle to the sprite
  1437. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1438. //-------------------------------------------------------------------------
  1439.  
  1440. SPRERROR EXPENTRY CmnSprQuerySpritePosition(HCSSPRITE hsSprite,
  1441.                                             PPOINTL pptlPos);
  1442. //-------------------------------------------------------------------------
  1443. // This function returns the current position of the sprite.  Note that
  1444. // a sprite has a current position even if it is hidden.
  1445. //
  1446. // Input:  hsSprite - handle to the sprite
  1447. // Output:  pptlPos - points to the current position
  1448. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1449. //-------------------------------------------------------------------------
  1450.  
  1451. SPRERROR EXPENTRY CmnSprQuerySpriteSize(HCSSPRITE hsSprite,PSIZEL pszlSize);
  1452. //-------------------------------------------------------------------------
  1453. // This function returns the current size of the sprite.
  1454. //
  1455. // Input:  hsSprite - handle to the sprite
  1456. // Output:  pszlSize - points to the current size
  1457. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1458. //-------------------------------------------------------------------------
  1459.  
  1460. SPRERROR EXPENTRY CmnSprQuerySpriteRect(HCSSPRITE hsSprite,PRECTL prclRect);
  1461. //-------------------------------------------------------------------------
  1462. // This function returns the bounding rectangle of the sprite at its
  1463. // current position.
  1464. //
  1465. // Input:  hsSprite - handle to the sprite
  1466. // Output:  prclRect - points to the current bounding rectangle
  1467. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1468. //-------------------------------------------------------------------------
  1469.  
  1470. SPRERROR EXPENTRY CmnSprSetSpriteVisibility(HPS hpsDraw,
  1471.                                             HCSSPRITE hsSprite,
  1472.                                             BOOL bVisible);
  1473. //-------------------------------------------------------------------------
  1474. // This function shows or hides a sprite.
  1475. //
  1476. // Input:  hpsDraw - handle to the HPS to draw in once the sprite is
  1477. //                   shown or hidden
  1478. //         hsSprite - handle to the sprite
  1479. //         bVisible - new visibility state
  1480. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1481. //-------------------------------------------------------------------------
  1482.  
  1483. SPRERROR EXPENTRY CmnSprQuerySpriteVisibility(HCSSPRITE hsSprite,
  1484.                                               PBOOL pbVisible);
  1485. //-------------------------------------------------------------------------
  1486. // This function returns the visibility state of the sprite
  1487. //
  1488. // Input:  hsSprite - handle to the sprite
  1489. // Output:  pbVisible - points to the visibility state
  1490. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1491. //-------------------------------------------------------------------------
  1492.  
  1493. SPRERROR EXPENTRY CmnSprDrawSprite(HPS hpsDraw,HCSSPRITE hsSprite);
  1494. //-------------------------------------------------------------------------
  1495. // This function draws a sprite
  1496. //
  1497. // Input:  hpsDraw - handle to the HPS to draw the sprite in
  1498. //         hsSprite - handle to the sprite
  1499. // Returns:  SPR_ERR_NOERROR if successful, SPR_ERR_* constant otherwise
  1500. //-------------------------------------------------------------------------
  1501. #endif                           // #ifdef INCL_CMNSPR
  1502.  
  1503. #ifdef INCL_CMNSTR
  1504. //-------------------------------------------------------------------------
  1505. // String routines
  1506. //-------------------------------------------------------------------------
  1507.  
  1508. USHORT EXPENTRY CmnStrQueryWordCount(PCHAR pchLine);
  1509. //-------------------------------------------------------------------------
  1510. // This function returns the number of words in the specified string
  1511. //
  1512. // Input:  pchLine - points to the string to query
  1513. // Returns:  number of words in the string
  1514. //-------------------------------------------------------------------------
  1515.  
  1516. SHORT EXPENTRY CmnStrQueryWordPosition(PCHAR pchLine,SHORT sWord);
  1517. //-------------------------------------------------------------------------
  1518. // This function finds the 0-based position of the specified word in the
  1519. // specified string.
  1520. //
  1521. // Input:  pchLine - points to the string to search
  1522. //         sWord - specifies the word number
  1523. // Returns:  position of the word if successful, SQWP_ERROR otherwise
  1524. //-------------------------------------------------------------------------
  1525.  
  1526. SHORT EXPENTRY CmnStrQueryWordLength(PCHAR pchLine,SHORT sWord);
  1527. //-------------------------------------------------------------------------
  1528. // This function returns the length of the word specified.
  1529. //
  1530. // Input:  pchLine - points to the string to search
  1531. //         sWord - specifies the word number
  1532. // Returns:  length of the word if successful, SQWP_ERROR otherwise
  1533. //-------------------------------------------------------------------------
  1534.  
  1535. BOOL EXPENTRY CmnStrQueryWord(PCHAR pchLine,
  1536.                               SHORT sWord,
  1537.                               PCHAR pchWord,
  1538.                               USHORT usSzWord);
  1539. //-------------------------------------------------------------------------
  1540. // This function extracts a word non-destructively from the specified line
  1541. // and copies it to the specified buffer.
  1542. //
  1543. // Input:  pchLine - points to the line to parse
  1544. //         sWord - contains the 0-based word number to extract
  1545. //         usSzWord - contains the size of the buffer pointed to by pchWord
  1546. // Output:  pchWord - points to the extracted word
  1547. // Returns:  TRUE if successful, FALSE otherwise
  1548. //-------------------------------------------------------------------------
  1549.  
  1550. BOOL EXPENTRY CmnStrConvertToNumber(PCHAR pchString,
  1551.                                     PVOID pvResult,
  1552.                                     USHORT usType);
  1553. //-------------------------------------------------------------------------
  1554. // This function converts a string to a number.  This is more robust than the
  1555. // ato*() family since this positively indicates whether or not an error
  1556. // occurred.
  1557. //
  1558. // Input:  pchString - points to the string to convert
  1559. //         usType - a combination of one SCTN_TYPE_* and one SCTN_ATTR_*
  1560. //                  constants.
  1561. // Output:  pvResult - points to the resulting number
  1562. // Returns:  TRUE if successful, FALSE otherwise
  1563. //-------------------------------------------------------------------------
  1564.  
  1565. SHORT EXPENTRY CmnStrParseLine(PCHAR pchLine,
  1566.                                PCSLINEDESC pcFormat,
  1567.                                USHORT usNumRecs,
  1568.                                PBYTE pbBuf);
  1569. //-------------------------------------------------------------------------
  1570. // This function parses the specified line, whose format is described by an
  1571. // array of CSLINEDESC structures (acFormat).  If the usType field of a
  1572. // CSLINEDESC record is blank, then usLength bytes are skipped in the
  1573. // result buffer, allowing the caller to have other fields that are not to
  1574. // be filled in by this function.
  1575. //
  1576. // Upon exit, the usType field is either SPL_FOUND or SPL_NOTFOUND, indicating
  1577. // whether or not a non-whitespace character was found in the usOffset<->
  1578. // usOffset+usLength-1 positions of the line.
  1579. //
  1580. // For each field descriptor, the corresponding field is extracted, and
  1581. // CmnStrConvertToNumber is called if the destination type is numeric.
  1582. //
  1583. // Notes:
  1584. // For numeric types, an SPL_ATTR_* constant may be or'd to specify
  1585. //    whether or not the number is in decimal or hexidecimal
  1586. // For SPL_TYPE_STRING fields, usLength also specifies the width of the
  1587. //    placeholder in pbBuf and does not include the trailing '\0'.
  1588. // For SPL_TYPE_RESERVED fields, usType always equals SPL_FOUND on return.
  1589. //
  1590. // Input:  pchLine - points to the line to parse
  1591. //         pcFormat - points to an array of CSLINEDESC describing the line
  1592. //         usNumRecs - specifies the number of CSLINEDESC records are
  1593. //                     pointed to by acFormat
  1594. // Output:  pcFormat - usType field indicates found/not found status of the
  1595. //                     field
  1596. //          pbBuf - points to the parsed line
  1597. // Returns:  the number of fields found is successful, SPL_ERROR otherwise
  1598. //-------------------------------------------------------------------------
  1599.  
  1600. BOOL EXPENTRY CmnStrParseCommandLine(PCHAR *ppchArgs,
  1601.                                      USHORT usNumArgs,
  1602.                                      PCSCMDDESC pccdFormat,
  1603.                                      USHORT usNumSwitches,
  1604.                                      PFNCMDERR pfnError);
  1605. //-------------------------------------------------------------------------
  1606. // This function parses the command line as described by the pccdFormat
  1607. // switch description array.
  1608. //
  1609. // Input:  ppchArgs - points to an array of pointers to the command-line
  1610. //                    arguments
  1611. //         usNumArgs - specifies the number of command-line arguments,
  1612. //                     including the program name (ppchArgs[0])
  1613. //         pccdFormat - points to an array of CSCMDDESC structs describing
  1614. //                      the valid command-line arguments:
  1615. //
  1616. //                      usId - specifies a unique id assigned to the switch.
  1617. //                             This is used by the pfnCallback function.
  1618. //                      achSwitch - points to the switch string, without the
  1619. //                                  leading "-" or "/".
  1620. //                      usNumArgs - specifies the number of arguments the
  1621. //                                  switch requires.
  1622. //                      usFlags - specifies a combination of SPCL_FLG_*
  1623. //                                constants describing the switch's attributes:
  1624. //
  1625. //                                SPCL_CASESENSITIVE specifies that achSwitch
  1626. //                                                   is case-sensitive.
  1627. //                                SPCL_SUBSTRING     specifies that achSwitch
  1628. //                                                   is a substring of what
  1629. //                                                   will be encountered on
  1630. //                                                   the command line (e.g
  1631. //                                                   "-FPa" where "FP" is the
  1632. //                                                   switch).
  1633. //                                SPCL_ARGCONCAT     (valid only with
  1634. //                                                   SPCL_SUBSTRING)
  1635. //                                                   specifies that the first
  1636. //                                                   argument is concatenated
  1637. //                                                   to the switch name (e.g.
  1638. //                                                   "-FPa" where "a" is the
  1639. //                                                   argument)
  1640. //                      pfnCallback - points to a function which is called
  1641. //                                    whenever a switch match is found.  It
  1642. //                                    takes the following arguments:
  1643. //
  1644. //                                    USHORT - the identifier of the switch as
  1645. //                                             specified in the CSCMDDESC
  1646. //                                             structure.
  1647. //                                    PCHAR * - the switch arguments.
  1648. //                                    USHORT - the number of arguments.
  1649. //                                    Returns - TRUE if successful, FALSE
  1650. //                                              otherwise.
  1651. //         usNumSwitches - specifies the number of CSCMDDESC structures are
  1652. //                         pointed to by pccdFormat.
  1653. //         pfnError - points to an error function which is called whenever
  1654. //                    CmnStrParseCommandLine encounters an error.  It takes
  1655. //                    a single USHORT - specifying a SPCL_ERR_* error id -
  1656. //                    as its argument.
  1657. // Returns:  TRUE if successful, FALSE otherwise
  1658. //-------------------------------------------------------------------------
  1659.  
  1660. BOOL EXPENTRY CmnStrPadString(PCHAR pchString,
  1661.                               USHORT usSide,
  1662.                               USHORT usLength,
  1663.                               CHAR chPad);
  1664. //-------------------------------------------------------------------------
  1665. // This function pads a string to the specified length with the specified
  1666. // character.  It is assumed that the string is large enough to contain
  1667. // the result.
  1668. //
  1669. // Input:  pchString - points to the string to pad.  On exit, the string
  1670. //                     is padded
  1671. //         usSide - specifies the side on which to pad.  It can be SPS_LEFT
  1672. //                  or SPS_RIGHT.
  1673. //         usLength - specifies the desired length of the string.
  1674. //         chPad - specifies the character to pad with.
  1675. // Returns:  TRUE if successful, FALSE otherwise
  1676. //-------------------------------------------------------------------------
  1677.  
  1678. BOOL EXPENTRY CmnStrStripSpace(PCHAR pchString,USHORT usOptions);
  1679. //-------------------------------------------------------------------------
  1680. // This function removes the whitespace from the beginning or the end of the
  1681. // specified string.
  1682. //
  1683. // Input:  pchString - points to the string to strip
  1684. //         usOptions - SPS_LEFT, SPS_RIGHT, or a combination of both
  1685. //                     to specify from which side(s) the whitespace should
  1686. //                     be removed
  1687. // Returns:  TRUE if successful, FALSE otherwise
  1688. //-------------------------------------------------------------------------
  1689. #endif                           // #ifdef INCL_CMNSTR
  1690.  
  1691. #ifdef INCL_CMNVIO
  1692. //-------------------------------------------------------------------------
  1693. // Screen I/O routines
  1694. //-------------------------------------------------------------------------
  1695.  
  1696. BOOL EXPENTRY CmnVioLoadMessage(PCHAR pchMsgFile,
  1697.                                 ULONG ulId,
  1698.                                 PCHAR pchBuf,
  1699.                                 ULONG ulSzBuf);
  1700. //-------------------------------------------------------------------------
  1701. // This function loads a message from the specified message file.
  1702. //
  1703. // Input:  pchMsgFile - pointer to the message file name to load from
  1704. //         ulId - id of the message to load
  1705. //         pchBuf - pointer to the receiving buffer
  1706. //         ulSzBuf - size of the buffer pointed to by pchBuf
  1707. // Output:  pchBuf - points to the message text
  1708. // Returns:  TRUE if successful, FALSE otherwise
  1709. //-------------------------------------------------------------------------
  1710.  
  1711. BOOL EXPENTRY CmnVioDisplayMessage(PCHAR pchMsgFile,ULONG ulId,...);
  1712. //-------------------------------------------------------------------------
  1713. // This function puts a message to the screen in character mode.
  1714. //
  1715. // Input:  pchMsgFile - pointer to the message file name to load from
  1716. //         ulId - id of the message to load
  1717. // Returns:  TRUE if successful, FALSE otherwise
  1718. //-------------------------------------------------------------------------
  1719.  
  1720. BOOL CmnVioGetString(PCHAR pchBuf,ULONG ulSzBuf,ULONG ulOptions);
  1721. //-------------------------------------------------------------------------
  1722. // This function gets a string from the user.  The behavior of this
  1723. // function can be influenced by the options specified:
  1724. //
  1725. //    VGS_UNREADABLE    - the string should be unreadable.
  1726. //
  1727. // This function requires that the ANSI device driver is loaded.
  1728. //
  1729. // Input:  pchBuf - points to the buffer to hold the result
  1730. //         ulSzBuf - specifies the size of the buffer pointed to by pchBuf
  1731. //         ulOptions - one or more VGS_* constants
  1732. // Output:  pchBuf - points to the buffer containing the result
  1733. // Returns:  TRUE if successful, FALSE otherwise
  1734. //-------------------------------------------------------------------------
  1735. #endif                           // #ifdef INCL_CMNVIO
  1736.  
  1737. #ifdef INCL_CMNWIN
  1738. //-------------------------------------------------------------------------
  1739. // Windowing routines
  1740. //-------------------------------------------------------------------------
  1741.  
  1742. SHORT EXPENTRY CmnWinDisplayMessage(HWND hwndParent,
  1743.                                     HWND hwndOwner,
  1744.                                     ULONG ulStyle,
  1745.                                     HMODULE hmDll,
  1746.                                     USHORT usId,
  1747.                                     USHORT usHelpId,...);
  1748. //-------------------------------------------------------------------------
  1749. // This function puts a message to the screen in PM mode (using WinMessageBox).
  1750. // The title of the message box is assumed to have the message id usId|0x8000.
  1751. //
  1752. // Input:  hwndParent - handle of the parent window
  1753. //         hwndOwner - handle of the owning window
  1754. //         ulStyle - specifies the WinMessageBox styles
  1755. //         hmDll - handle of the DLL containing the message
  1756. //         usId - specifies the id of the message to load
  1757. //         usHelpId - specifies the id of the corresponding help panel
  1758. // Returns:  TRUE if successful, FALSE otherwise
  1759. //-------------------------------------------------------------------------
  1760.  
  1761. VOID EXPENTRY CmnWinCenterWindow(HWND hwndCenter);
  1762. //-------------------------------------------------------------------------
  1763. // This function centers the window within its parent
  1764. //
  1765. // Input:  hwndCenter - handle of the window to center
  1766. //-------------------------------------------------------------------------
  1767.  
  1768. BOOL EXPENTRY CmnWinSavePosition(HWND hwndWindow,
  1769.                                  HINI hiniProfile,
  1770.                                  PCHAR pchAppl,
  1771.                                  PCHAR pchKey);
  1772. //-------------------------------------------------------------------------
  1773. // This function saves the current position of the specified window in the
  1774. // specified .INI file
  1775. //
  1776. // Input:  hwndWindow - specifies the window to save
  1777. //         hiniProfile - specifies the profile to save to
  1778. //         pchAppl - specifies the application name to save as
  1779. //         pchKey - specifies the key name to save as
  1780. // Returns:  TRUE if successful, FALSE otherwise
  1781. //-------------------------------------------------------------------------
  1782.  
  1783. BOOL EXPENTRY CmnWinRestorePosition(HWND hwndWindow,
  1784.                                     HINI hiniProfile,
  1785.                                     PCHAR pchAppl,
  1786.                                     PCHAR pchKey);
  1787. //-------------------------------------------------------------------------
  1788. // This function restores the current position of the specified window from the
  1789. // specified .INI file
  1790. //
  1791. // Input:  hwndWindow - specifies the window to restore
  1792. //         hiniProfile - specifies the profile to restore from
  1793. //         pchAppl - specifies the application name to restore from
  1794. //         pchKey - specifies the key name to restore from
  1795. // Returns:  TRUE if successful, FALSE otherwise
  1796. //-------------------------------------------------------------------------
  1797.  
  1798. BOOL EXPENTRY CmnWinSavePosToBuffer(HWND hwndWindow,PCWPOSITION pcpPosition);
  1799. //-------------------------------------------------------------------------
  1800. // This function saves the current position of the specified window in the
  1801. // specified buffer
  1802. //
  1803. // Input:  hwndWindow - specifies the window to save
  1804. // Output:  pcpPosition - points to the variable containing the size and
  1805. //                        position data
  1806. // Returns:  TRUE if successful, FALSE otherwise
  1807. //-------------------------------------------------------------------------
  1808.  
  1809. BOOL EXPENTRY CmnWinRestorePosFromBuffer(HWND hwndWindow,
  1810.                                          PCWPOSITION pcpPosition);
  1811. //-------------------------------------------------------------------------
  1812. // This function restores the current position of the specified window from the
  1813. // specified buffer
  1814. //
  1815. // Input:  hwndWindow - specifies the window to restore
  1816. //         pcpPosition - points to the variable containing the size and
  1817. //                       position data
  1818. // Returns:  TRUE if successful, FALSE otherwise
  1819. //-------------------------------------------------------------------------
  1820. #endif                           // #ifdef INCL_CMNWIN
  1821.  
  1822. #ifdef __cplusplus
  1823. }
  1824. #endif                           // #ifdef __cplusplus
  1825.  
  1826. #pragma pack()
  1827.  
  1828. #endif                           // #ifndef COMMONLIB_INCLUDED
  1829.